Home Assistant

Home Assistant MCP 서버는 조명, 스위치, 센서 및 기타 모든 Home Assistant 엔티티를 보고 제어할 수 있는 Model Context Protocol 서버입니다. 이 서버를 통해 AI 어시스턴트는 스마트 홈 장치와 상호작용하고 자동화 시나리오를 관리할 수 있습니다.

특징

다양한 스마트 홈 장치 제어 (조명, 스위치, 온도조절기 등)
센서 데이터 모니터링 및 분석
자동화 규칙 조회 및 관리
장면(Scene) 활성화 및 관리
스크립트 실행 및 관리
지역(Zone) 및 위치 관리
장치 상태 모니터링 및 알림
에너지 사용량 추적 및 분석
날씨 데이터 및 예보 접근
사용자 및 접근 권한 관리
그룹 및 영역 관리
미디어 플레이어 제어
보안 시스템 모니터링 및 제어
이벤트 및 로그 분석

API

리소스

homeassistant://states

모든 엔티티의 현재 상태 정보를 제공합니다.

homeassistant://states/{entity_id}

특정 엔티티의 상태 정보를 제공합니다.

homeassistant://services

사용 가능한 서비스 목록과 정보를 제공합니다.

homeassistant://history/{entity_id}

특정 엔티티의 상태 이력을 제공합니다.

도구

상태 관리

get_states

모든 엔티티의 현재 상태를 조회합니다. - 입력: 없음 - 출력: 모든 엔티티 ID, 상태, 속성 등을 포함한 상태 목록

get_state

특정 엔티티의 현재 상태를 조회합니다. - 입력: - entity_id: 엔티티 ID - 출력: 엔티티 상태 및 속성 정보

set_state

엔티티의 상태를 설정합니다. - 입력: - entity_id: 엔티티 ID - state: 새 상태 값 - attributes: (선택적) 새 속성 값 - 출력: 업데이트된 엔티티 상태

get_history

엔티티의 상태 이력을 조회합니다. - 입력: - entity_id: 엔티티 ID - start_time: (선택적) 시작 시간 - end_time: (선택적) 종료 시간 - minimal_response: (선택적) 최소한의 응답만 반환할지 여부 - significant_changes_only: (선택적) 중요한 변경 사항만 포함할지 여부 - 출력: 시간별 엔티티 상태 이력

서비스 호출

list_services

사용 가능한 모든 서비스를 나열합니다. - 입력: 없음 - 출력: 도메인별 서비스 목록 및 설명

call_service

서비스를 호출합니다. - 입력: - domain: 서비스 도메인 - service: 서비스 이름 - service_data: (선택적) 서비스 데이터 - target: (선택적) 대상 엔티티 또는 영역 - 출력: 서비스 호출 결과

turn_on

엔티티를 켭니다. - 입력: - entity_id: 엔티티 ID - parameters: (선택적) 추가 매개변수 (밝기, 색상 등) - 출력: 서비스 호출 결과

turn_off

엔티티를 끕니다. - 입력: - entity_id: 엔티티 ID - 출력: 서비스 호출 결과

toggle

엔티티 상태를 전환합니다. - 입력: - entity_id: 엔티티 ID - 출력: 서비스 호출 결과

자동화 관리

list_automations

모든 자동화를 나열합니다. - 입력: 없음 - 출력: 자동화 ID, 이름, 상태 등을 포함한 자동화 목록

get_automation

특정 자동화의 정보를 조회합니다. - 입력: - automation_id: 자동화 ID - 출력: 자동화 상세 정보

trigger_automation

자동화를 수동으로 트리거합니다. - 입력: - automation_id: 자동화 ID - variables: (선택적) 트리거 변수 - 출력: 트리거 결과

enable_automation

자동화를 활성화합니다. - 입력: - automation_id: 자동화 ID - 출력: 활성화 결과

disable_automation

자동화를 비활성화합니다. - 입력: - automation_id: 자동화 ID - 출력: 비활성화 결과

장면 관리

list_scenes

모든 장면을 나열합니다. - 입력: 없음 - 출력: 장면 ID, 이름 등을 포함한 장면 목록

activate_scene

장면을 활성화합니다. - 입력: - scene_id: 장면 ID - transition: (선택적) 전환 시간(초) - 출력: 활성화 결과

스크립트 관리

list_scripts

모든 스크립트를 나열합니다. - 입력: 없음 - 출력: 스크립트 ID, 이름 등을 포함한 스크립트 목록

run_script

스크립트를 실행합니다. - 입력: - script_id: 스크립트 ID - variables: (선택적) 스크립트 변수 - 출력: 실행 결과

엔티티 그룹 관리

list_groups

모든 엔티티 그룹을 나열합니다. - 입력: 없음 - 출력: 그룹 ID, 이름, 멤버 등을 포함한 그룹 목록

get_group

특정 그룹의 정보를 조회합니다. - 입력: - group_id: 그룹 ID - 출력: 그룹 상세 정보 및 멤버 목록

set_group_state

그룹의 상태를 설정합니다. - 입력: - group_id: 그룹 ID - state: 새 상태 값 - 출력: 업데이트된 그룹 상태

영역 관리

list_areas

모든 영역을 나열합니다. - 입력: 없음 - 출력: 영역 ID, 이름 등을 포함한 영역 목록

get_area

특정 영역의 정보를 조회합니다. - 입력: - area_id: 영역 ID - 출력: 영역 상세 정보

get_entities_by_area

특정 영역에 속한 모든 엔티티를 나열합니다. - 입력: - area_id: 영역 ID - 출력: 해당 영역의 엔티티 목록

장치 관리

list_devices

모든 장치를 나열합니다. - 입력: 없음 - 출력: 장치 ID, 이름, 모델, 제조사 등을 포함한 장치 목록

get_device

특정 장치의 정보를 조회합니다. - 입력: - device_id: 장치 ID - 출력: 장치 상세 정보

get_entities_by_device

특정 장치에 속한 모든 엔티티를 나열합니다. - 입력: - device_id: 장치 ID - 출력: 해당 장치의 엔티티 목록

미디어 플레이어 제어

play_media

미디어 플레이어에서 미디어를 재생합니다. - 입력: - entity_id: 미디어 플레이어 엔티티 ID - media_content_id: 미디어 콘텐츠 ID - media_content_type: 미디어 콘텐츠 유형 - 출력: 서비스 호출 결과

media_pause

미디어 재생을 일시 중지합니다. - 입력: - entity_id: 미디어 플레이어 엔티티 ID - 출력: 서비스 호출 결과

media_play

미디어 재생을 시작합니다. - 입력: - entity_id: 미디어 플레이어 엔티티 ID - 출력: 서비스 호출 결과

media_stop

미디어 재생을 중지합니다. - 입력: - entity_id: 미디어 플레이어 엔티티 ID - 출력: 서비스 호출 결과

set_volume_level

미디어 플레이어 볼륨을 설정합니다. - 입력: - entity_id: 미디어 플레이어 엔티티 ID - volume_level: 볼륨 레벨 (0.0 ~ 1.0) - 출력: 서비스 호출 결과

기후 장치 제어

set_temperature

온도조절기 온도를 설정합니다. - 입력: - entity_id: 온도조절기 엔티티 ID - temperature: 설정 온도 - hvac_mode: (선택적) HVAC 모드 - 출력: 서비스 호출 결과

set_hvac_mode

온도조절기 HVAC 모드를 설정합니다. - 입력: - entity_id: 온도조절기 엔티티 ID - hvac_mode: HVAC 모드 (heat, cool, auto 등) - 출력: 서비스 호출 결과

날씨 정보

get_weather

날씨 정보를 조회합니다. - 입력: - weather_entity_id: 날씨 엔티티 ID - 출력: 현재 날씨 상세 정보

get_forecast

날씨 예보를 조회합니다. - 입력: - weather_entity_id: 날씨 엔티티 ID - forecast_type: (선택적) 예보 유형 (daily, hourly) - 출력: 예보 데이터

사용 방법

설치 및 구성

사전 요구 사항:
실행 중인 Home Assistant 인스턴스
Home Assistant Long-Lived Access Token
MCP 서버 설치:
```
pip install homeassistant-mcp-server
```

Claude Desktop 구성:

{
  "mcpServers": {
    "homeassistant": {
      "command": "python",
      "args": ["-m", "homeassistant_mcp"],
      "env": {
        "HASS_URL": "https://your-home-assistant-url",
        "HASS_TOKEN": "your-long-lived-access-token",
        "HASS_VERIFY_SSL": "true"
      }
    }
  }
}

Home Assistant Long-Lived Access Token 생성:
Home Assistant 웹 UI에 로그인
프로필 페이지로 이동 (좌측 하단의 사용자 아이콘 클릭)
페이지 하단의 "Long-Lived Access Tokens" 섹션에서 새 토큰 생성
토큰 이름을 지정하고 "Create" 버튼 클릭
생성된 토큰을 안전하게 저장 (이 토큰은 다시 표시되지 않음)
구성 옵션:
HASS_URL: Home Assistant 인스턴스 URL
HASS_TOKEN: Long-Lived Access Token
HASS_VERIFY_SSL: SSL 인증서 확인 여부 (기본값: true)
HASS_CACHE_TTL: 캐시 수명(초) (기본값: 30)
HASS_LOG_LEVEL: 로그 수준 (기본값: INFO)
HASS_CONNECTION_TIMEOUT: 연결 타임아웃(초) (기본값: 10)

기본 사용 예시

엔티티 상태 조회:
```
get_states()
```

특정 엔티티 상태 조회:

get_state({
  entity_id: "light.living_room"
})

조명 켜기:

turn_on({
  entity_id: "light.living_room",
  parameters: {
    brightness_pct: 75,
    color_name: "warm_white"
  }
})

에어컨 설정:

set_temperature({
  entity_id: "climate.living_room",
  temperature: 22,
  hvac_mode: "cool"
})

장면 활성화:

activate_scene({
  scene_id: "scene.movie_night",
  transition: 2
})

자동화 실행:

trigger_automation({
  automation_id: "automation.morning_routine"
})

영역의 모든 장치 상태 조회:

get_entities_by_area({
  area_id: "living_room"
})

센서 데이터 이력 조회:

get_history({
  entity_id: "sensor.living_room_temperature",
  start_time: "2025-05-13T00:00:00Z",
  end_time: "2025-05-14T00:00:00Z"
})

날씨 정보 조회:

get_weather({
  weather_entity_id: "weather.home"
})

미디어 플레이어 제어:

play_media({
  entity_id: "media_player.living_room_speaker",
  media_content_id: "https://example.com/music.mp3",
  media_content_type: "music"
})

보안 고려사항

Home Assistant Long-Lived Access Token은 민감한 정보이므로 안전하게 관리해야 합니다.
토큰은 Home Assistant 인스턴스에 대한 전체 접근 권한을 제공할 수 있으므로 유출되지 않도록 특별히 주의하세요.
가능하다면 토큰의 권한을 최소한으로 제한하세요.
Home Assistant 인스턴스가 인터넷에 노출되어 있다면 HTTPS와 같은 안전한 연결 방식을 사용하세요.
자동화 및 스크립트 실행은 신중하게 수행하세요. 예기치 않은 동작이 발생할 수 있습니다.
보안 시스템 제어는 특별히 주의하여 관리하세요.

연결된 구성 요소

Apple Calendar - 자연어를 통해 MacOS Calendar와 상호작용
Google Calendar - 일정 확인, 시간 찾기, 이벤트 추가/삭제를 위한 Google Calendar 통합
Discord - 봇을 통해 Discord 길드에 연결하고 채널에서 메시지를 읽고 쓰는 서버
Telegram - Telethon 통합을 통한 페이지별 채팅 읽기, 메시지 검색 및 메시지 전송 기능

MCP 문서 앱 설치

iOS에 앱 설치하기

메뉴

문서 정보

링크된 문서

역링크

Home Assistant

Home Assistant

특징

API

리소스

homeassistant://states

homeassistant://states/{entity_id}

homeassistant://services

homeassistant://history/{entity_id}

도구

상태 관리

get_states

get_state

set_state

get_history

서비스 호출

list_services

call_service

turn_on

turn_off

toggle

자동화 관리

list_automations

get_automation

trigger_automation

enable_automation

disable_automation

장면 관리

list_scenes

activate_scene

스크립트 관리

list_scripts

run_script

엔티티 그룹 관리

list_groups

get_group

set_group_state

영역 관리

list_areas

get_area

get_entities_by_area

장치 관리

list_devices

get_device

get_entities_by_device

미디어 플레이어 제어

play_media

media_pause

media_play

media_stop

set_volume_level

기후 장치 제어

set_temperature

set_hvac_mode

날씨 정보

get_weather

get_forecast

사용 방법

설치 및 구성

기본 사용 예시

보안 고려사항

연결된 구성 요소